Real-Time Updates

The SAHAJ platform offers real-time notifications about critical DPDPA consent lifecycle events via Webhooks or RabbitMQ Queue subscriptions. This ensures your Data Flow (DF) and Consent Management Platform (CMP) always operate on the most current lawful basis, maintaining strict compliance.

Webhooks

Webhooks allow SAHAJ to push immediate updates directly to a secure HTTP endpoint you specify. This is the recommended method for receiving instant notifications.

1. Registering Your Webhook Endpoint

To begin receiving events, you must register a publicly accessible HTTPS endpoint in the SAHAJ platform configuration for your organization.

• Endpoint Requirement: Your endpoint MUST be served over HTTPS (SSL/TLS).
• Response Requirement: Your endpoint MUST respond with an HTTP status code of 200 OK and a body containing {"status": "ok"} within 10 seconds of receiving the payload. Any other status code (e.g., 4xx, 5xx) will be logged as a failure and trigger our retry mechanism.
• Testing: For initial development and testing, we recommend using ngrok to expose your local development server to the internet.

2. Mandatory Security & Authentication

Upon registering your webhook, SAHAJ provides a Shared Secret. This secret is crucial for validating the authenticity and integrity of the webhook payload.

Requirement	Value	Description
Header	X-Consent-Signature	The HTTP header containing the HMAC-SHA256 signature. This is a strict requirement.
Mechanism	HMAC-SHA256	The signature is computed using the Shared Secret and the raw JSON payload.

You MUST use this signature to verify that the request originated from the SAHAJ platform and that the payload has not been tampered with.

3. Real-Time Consent Events

The following critical events are streamed to your registered webhook in real-time. Each event is wrapped in a standard payload structure.

Standard Event Payload Structure

{
  "webhook_id": "unique_webhook_config_identifier",
  "event_id": "1231231312",
  "dp_id": "1231231",
  "df_id": "df_company_identifier",
  "dpr_id": "data_processor_identifier (if applicable)",
  "event": "EVENT_NAME_CODE",
  "environment": "testing | production",
  "timestamp": "2025-10-02T11:30:00.000000+00:00",
  "message": "Event-specific description or status message."
  // Additional event-specific data (e.g., purpose_id, consent_artifact_id) will be included here.
}

Event Details Table

Event Name	Description	When Triggered	Why Triggered	Action Required by DF
CONSENT_GRANTED	New, valid consent artifact created.	DP takes affirmative action on a compliant consent notice.	Establish the lawful basis for processing.	Begin data processing for the specified purpose(s).
CONSENT_VALIDATED	Active consent confirmation (the 'Green Light').	Every time the DF attempts to access/process DP's personal data for a specific purpose.	Legal checkpoint for real-time compliance.	Proceed with processing only if consent is VALID; halt otherwise.
CONSENT_UPDATED	DP modified the scope, terms, or purposes of a previously granted consent.	DP modifies the scope or details of an existing consent via the CMS.	DF must adjust processing activities to align with current, granular preferences.	Adjust processing activities immediately to strictly align with the modified consent.
CONSENT_RENEWED	Time-bound consent has been successfully renewed by the Data Principal.	A time-bound consent is approaching expiry and the DP extends the period.	Maintain the lawful basis without interruption.	Continue processing under the renewed consent terms.
CONSENT_WITHDRAWN	Critical, real-time alert: DP has revoked their consent.	DP explicitly revokes consent via the CMS dashboard or linked interface.	Enforce the Right to Withdraw Consent; DF must cease processing.	Immediately cease all processing activities related to the withdrawn purpose(s).
CONSENT_EXPIRED	Consent period has lapsed without renewal and is no longer valid.	A time-bound consent reaches its pre-determined end date.	Lawful basis of consent has ended; processing must immediately cease.	Stop processing activities related to the expired consent.
DATA_ERASURE_MANUAL_TRIGGERED	DP manually requested deletion/anonymization (Right to Erasure).	DP submits a request to the CMS for deletion or anonymization.	Initiate the DF's process to delete or anonymize personal data.	Immediately delete or anonymize the data as requested by the DP.
DATA_ERASURE_RETENTION_TRIGGERED	Personal data must be erased/anonymized because the retention period has expired.	Original processing purpose is no longer served, or the stated retention period has lapsed.	Enforce DPDPA obligation that personal data cannot be stored indefinitely.	Delete or anonymize data according to the data retention policy.
DATA_UPDATE_REQUESTED	DP has submitted a request to update or correct their personal data.	DP submits a request to the CMS to update or correct inaccuracies.	Enforce the Right to Correction and Completion.	Validate the request and update internal records and active processing pipelines accordingly.
GRIEVANCE_RAISED	DP has submitted a formal grievance or complaint.	DP uses the CMS or linked portal to log a formal complaint.	Initiate the DF's mandatory Grievance Redressal process.	Review and address the grievance per internal and regulatory procedures.
WEBHOOK_TEST	Test event used to confirm successful registration and signature verification.	N/A (Triggered by the system for testing).	Confirm successful webhook setup and signature validation for production events.	Acknowledge receipt and return {"status": "ok"}.
CONSENT_AUDIT_LOG	General log event for all consent-related actions for audit trail purposes.	Whenever a consent event (e.g., Granted, Withdrawn, Updated) occurs.	Maintain an immutable, regulatory-compliant audit trail of all consent activity.	Log the event details securely for future compliance and audit checks.

---

Webhook Implementation Guide

To ensure a robust, production-ready system, your webhook handler must:

1. Read the raw request body.
2. Extract the signature from the X-Consent-Signature header.
3. Compute the HMAC-SHA256 signature using your Shared Secret and the raw body.
4. Compare the computed signature with the received signature in a timing-safe manner.
5. If verification passes, process the event and return 200 OK with {"status": "ok"}.
6. If verification fails, return 401 Unauthorized.

Example Implementations

Python (FastAPI)

from fastapi import FastAPI, Request, Header, HTTPException
from typing import Optional
import hmac, hashlib, json, logging

app = FastAPI()
WEBHOOK_SECRET = "YOUR_SHARED_SECRET_FROM_SAHAJ"
WEBHOOK_AUTH_HEADER = "X-Consent-Signature"

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger()

def verify_signature(raw_payload: bytes, signature: str) -> bool:
    computed_sig = hmac.new(
        WEBHOOK_SECRET.encode(),
        msg=raw_payload,
        digestmod=hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(computed_sig, signature)

@app.post("/webhook")
async def receive_webhook(request: Request, x_consent_signature: Optional[str] = Header(None)):
    raw_body = await request.body()
    if not x_consent_signature:
        raise HTTPException(status_code=401, detail="Missing signature header")
    if not verify_signature(raw_body, x_consent_signature):
        logger.error(f"SECURITY ALERT: Invalid signature: {x_consent_signature}")
        raise HTTPException(status_code=401, detail="Invalid signature")
    try:
        payload = json.loads(raw_body)
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON payload")

    event_type = payload.get("event")
    logger.info(f"Received verified event: {event_type} (ID: {payload.get('event_id')}) for DP ID: {payload.get('dp_id')}")

    if event_type == "CONSENT_WITHDRAWN":
        logger.warning(f"ACTION REQUIRED: Consent withdrawn for DP: {payload.get('dp_id')}.")

    return {"status": "ok"}

Node.js (Express)

const express = require("express");
const bodyParser = require("body-parser");
const crypto = require("crypto");

const app = express();
const port = 3000;
const WEBHOOK_SECRET = "YOUR_SHARED_SECRET_FROM_SAHAJ";
const WEBHOOK_AUTH_HEADER = "X-Consent-Signature";

app.use(
  bodyParser.json({
    verify: (req, res, buf) => {
      req.rawBody = buf;
    },
  })
);

function verifySignature(rawBody, signature) {
  const computedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(computedSignature, "hex"),
    Buffer.from(signature, "hex")
  );
}

app.post("/webhook", (req, res) => {
  const signature = req.get(WEBHOOK_AUTH_HEADER);
  if (!signature)
    return res.status(401).send({ error: "Missing signature header" });

  if (!verifySignature(req.rawBody, signature)) {
    console.error(`SECURITY ALERT: Invalid signature received.`);
    return res.status(401).send({ error: "Invalid signature" });
  }

  const payload = req.body;
  console.log(
    `Received verified event: ${payload.event} (ID: ${payload.event_id}) for DP ID: ${payload.dp_id}`
  );
  res.status(200).send({ status: "ok" });
});

app.listen(port, () =>
  console.log(`Webhook server listening at http://localhost:${port}`)
);

---

Testing and Deployment

Testing Your Webhook

1. Set up ngrok: Run ngrok http <YOUR_PORT> to get a public HTTPS URL.
2. Register: Use the public HTTPS URL in the SAHAJ platform configuration.
3. Test Event: Use the "Test Webhook" button in the SAHAJ UI to receive a WEBHOOK_TEST event.
4. Verification: Your handler must successfully verify the signature and log the event. If successful, ensure the HTTP response is 200 OK with the body {"status": "ok"}.

Production Readiness

• Data Processors: You must also register separate webhooks for each of your Data Processors (DPs) that require real-time consent updates. Each DP will receive a unique Shared Secret.
• Environment Promotion: After successful testing, you must explicitly change the environment of your registered webhook from Testing to Production within the SAHAJ platform.
• Retry Mechanism: If your endpoint fails to respond with a 200 OK within the 10-second timeout, we will retry the delivery up to 3 times. The retries use a configurable interval which can be set to either exponential backoff or fixed interval.
• Event Replay & Failed Events API:
  • We store event logs for the last 15 days.
  • If needed, you can use the Replay API to replay events from a specific event_id and timestamp.
  • We provide separate Failed Events APIs which allow you to query, view, and manually trigger redelivery of any failed webhook updates.

RabbitMQ Queue Subscriptions

For organizations or DPs handling high event volumes, SAHAJ provides RabbitMQ-based delivery as an alternative to Webhooks.

1. Enabling RabbitMQ Consent Updates

• Enable Consent Updates via RabbitMQ in SAHAJ integration settings.
• SAHAJ provisions a dedicated RabbitMQ vhost with unique credentials.

2. Credentials & Security

• Data Flow (DF): Each DF gets a dedicated queue with unique username/password.
• Data Processors (DPs): Each DP gets an individual read-only queue.
• Permissions are scoped strictly to consuming messages from their assigned queue.

3. Event Delivery

All consent lifecycle events are streamed:

• CONSENT_GRANTED, CONSENT_WITHDRAWN, CONSENT_UPDATED, CONSENT_EXPIRED,
• DATA_ERASURE_MANUAL_TRIGGERED, DATA_UPDATE_REQUESTED, GRIEVANCE_RAISED,
• Additional: CONSENT_VALIDATED, CONSENT_RENEWED, CONSENT_AUDIT_LOG

4. Consumption

• Connect using provided RabbitMQ hostname, port, username, and password.
• Subscribe using any RabbitMQ client (e.g., Python pika, Node.js amqplib).
• Messages are JSON payloads identical to webhook bodies.

5. High-Volume Handling

• RabbitMQ ensures at-least-once delivery → consumers must be idempotent.
• If offline, messages remain queued until consumed.